home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / monitory / amigamonitor / amon.doc < prev    next >
Text File  |  1987-05-03  |  15KB  |  482 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                       *1 
  9.                            Amiga Monitor User's Guide
  10.  
  11.                                   Version 1.13
  12.                                  April 29, 1987
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                                   J. S. Voris
  24.                                  Quma Software
  25.                                   P.O. Box 593
  26.                              Hunt Valley, MD  21030
  27.                               BBS: (301) 666-9109
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.               « Copyright 1986, 1987 Jim Voris. All Rights Reserved
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.      Version 1.13          Amiga Monitor User's Guide                Page 1
  64.  
  65.  
  66.                                     PREFACE
  67.  
  68.           AmigaMon is shareware software. It may be freely
  69.           distributed so long as it is unchanged, and this document
  70.           is distributed with it. If you use AmigaMon at work or for
  71.           commercial purposes, a contribution of  $15 is requested.
  72.           Please send contributions to me at the address shown on the
  73.           title page of this document. I make NO warranty of any kind
  74.           on the merchantability, etc. of AmigaMon. It's provided as
  75.           is.  
  76.  
  77.           Source code for AmigaMon is available separately at a
  78.           negotiable price.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.               « Copyright 1986, 1987 Jim Voris. All Rights Reserved
  121. K3
  122.  
  123.      Version 1.13          Amiga Monitor User's Guide                Page 2
  124.  
  125.  
  126.      1.0 Introduction     
  127. M
  128.      The Amiga Monitor is designed to monitor the dynamics of the Amiga's
  129.      multitasking operating system. By selecting from standard Amiga
  130.      pull-down menus it will dynamically display: 
  131.  
  132.      o - Open Files: Shows volume names and the files on that volume that
  133.          have  open locks.  
  134.  
  135.      o - Active Tasks: Shows a list of all the active tasks in the
  136.          system.  
  137.  
  138.      o - Free Memory: Shows a list of the free memory in the system.  
  139.  
  140.      o - Resources: Shows a list of resources known to the system.  
  141.  
  142.      o - Devices: Shows a list of devices known to the system.  
  143.  
  144.      o - Interrupts: Shows a list of interrupts known to the system.  
  145.  
  146.      o - Libraries: Shows a list of the libraries known to the system.  
  147.  
  148.      o - Ports: Shows a list of the ports known to the system.  
  149.  
  150.  
  151.      In addition, another option allows the dynamic display of the
  152.      contents of memory.  
  153.  
  154.      AmigaMon was born from my own desire to see what was going on inside
  155.      the Amiga. It was modeled to some extent to look like a similar tool
  156.      available on DEC's RSX-11M-PLUS operating system: RMD. The goal in
  157.      its writing was to display as much as possible about what was going
  158.      on inside the box without getting in the way of whatever was running.
  159.      I think that generally I have succeeded, though the final version is
  160.      somewhat larger than I had hoped it would be.  
  161.  
  162. K3     2.0 General Description    
  163. M
  164.      AmigaMon can be run from either the Workbench or from the CLI. When
  165.      first started, it displays a blank screen, with a screen title bar.
  166.      The menu options are displayed by hitting the right mouse button.
  167.      Choosing an option from the menu fills the display with the requested
  168.      information.  
  169.  
  170.      Note that ALL the different displays in AmigaMon are DYNAMIC, i.e.
  171.      the information that AmigaMon displays is sampled at the rate
  172.      specified from the update menu (default rate is once every 2
  173.      seconds).  
  174.  
  175.      The actual use of AmigaMon should be fairly self explanatory in that
  176.      it uses the standard Intuition interface of pull-down menus, etc. The
  177.      following section on 'options' provides greater detail about what the
  178.  
  179.  
  180.               « Copyright 1986, 1987 Jim Voris. All Rights Reserved
  181.  
  182.  
  183.      Version 1.13          Amiga Monitor User's Guide                Page 3
  184.  
  185.  
  186.      menu items mean.  
  187.  
  188. K3     3.0 Options     
  189. M
  190.      The main menu of AmigaMon contains the following items: 
  191.  
  192.           Project  Monitor  View  Set  Page  Update Rate 
  193.  
  194.      Each of these is discussed in greater detail in the following
  195.      sections.  
  196.  
  197. K3     3.1 Project     
  198. M
  199.      The Project menu has items that are related to all the different
  200.      screens of Amigamon. These items are: About, Hide/Show Title, Stop
  201.      Update, Snapshot, and Exit.  
  202.  
  203.      o - About: displays a requester that provides some information about
  204.          this particular version of AmigaMon.  
  205.  
  206.      o - Hide/Show Title: toggles to either hide the screen title, or show
  207.          it. Note that when the screen title is hidden, the status line
  208.          appears. The status line is updated at the update rate selected
  209.          from the Update menu. It shows which display is currently active,
  210.          percent idle CPU, the amount of free memory in the system, and
  211.          the system time.  
  212.  
  213.      o - Stop Update: when selected, will clear the currently active
  214.          screen, and leave only the status line active.  
  215.  
  216.      o - Snapshot: AmigaMon will write the current screen contents
  217.          (including status line), to standard out. You can redirect
  218.          standard out on the command line you use to invoke AmigaMon. For
  219.          example, to redirect snapshots to the file snap.log, use the
  220.          command line: 
  221.  
  222.               run AmigaMon > snap.log 
  223.  
  224.          The snapshot feature has not been tested when AmigaMon is run via
  225.          an icon from the workbench.  
  226.  
  227.      o - Exit: exit AmigaMon. AmigaMon will shut down the active screen,
  228.          release all its memory and exit.  
  229.  
  230.  
  231. K3     3.2 Monitor     
  232. M
  233.      The monitor menu allows you to select among monitoring the open files
  234.      in the system as well as the various lists that have their listheads
  235.      in the ExecBase structure.  
  236.  
  237.      The open files display shows the volume names and the files on that
  238.  
  239.  
  240.               « Copyright 1986, 1987 Jim Voris. All Rights Reserved
  241.  
  242.  
  243.      Version 1.13          Amiga Monitor User's Guide                Page 4
  244.  
  245.  
  246.      volume that have outstanding file locks. For each file, it displays
  247.      the last modify date for the file, and for non-directory files, it
  248.      displays the size of the file in bytes. Note that this display is
  249.      DYNAMIC. In order for AmigaMon to get all the information for the
  250.      open files display, it must access the disk. This will generally
  251.      occur only when AmigaMon has detected a change in the number of open
  252.      locks on a volume.  
  253.  
  254.      The lists in the ExecBase structure that are monitored are: MemList
  255.      (free memory), ResourceList (resources), DeviceList (devices),
  256.      IntrList  (interrupts), LibList (libraries), PortList (ports),
  257.      TaskReady and TaskWait.  For these list based displays to be useful,
  258.      you really need to reference the appropriate structures that define
  259.      these lists. These structures are defined in the ROM Kernal Manual,
  260.      as well as in the appropriate 'C' include files. AmigaMon extracts
  261.      what I thought would be the most interesting portion of each type of
  262.      list for display. The column headings for each display should be
  263.      self-explanatory if you also refer to the appropriate structure
  264.      definition in the RKM.  
  265.  
  266. K3     3.3 View     
  267. M
  268.      The view menu lets you 'view' memory. There are two menu items: data
  269.      and instructions. The only one currently implemented is the data
  270.      view.  Selecting the data item will display memory beginning at the
  271.      address specified from the 'Set' menu. Data may be viewed as either
  272.      bytes, 2 byte words and 4 byte long words as selected from the 'Set'
  273.      menu. In addition to the hex display of memory data, the ASCII byte
  274.      representation of memory is displayed at the far right of the screen.
  275.      The 'Page' menu allows you to move forward and backward in memory one
  276.      page at a time.  
  277.  
  278.      When implemented, selecting the view instructions item will allow the
  279.      display of memory as instructions, i.e. a disassembler.  
  280.  
  281. K3     3.4 Set     
  282. M
  283.      The 'Set' menu allows you to set the starting address to be used when
  284.      viewing memory as data or instructions. It also allows you to set the
  285.      size of the data word to be displayed on the view data screen as
  286.      either 1 byte, 2 bytes, or 4 bytes.  
  287.  
  288.      When setting the starting address, a requester appears on the screen.
  289.      It has a drag bar so that if it's covering a part of the screen that
  290.      you need to see, you can just drag it to someplace out of the way.  
  291.  
  292.      The requester also has a 'BCPL' gadget. Selecting the BCPL gadget
  293.      multiplies the currently selected address by four. This is so that
  294.      you can enter a BCPL address and have AmigaMon convert it to a
  295.      machine address for you. Note that AmigaMon has no notion of whether
  296.      the address you have entered needs BCPL conversion or not. If you
  297.      don't know what a BCPL address is, you shouldn't use the BCPL gadget.
  298.  
  299.  
  300.               « Copyright 1986, 1987 Jim Voris. All Rights Reserved
  301.  
  302.  
  303.      Version 1.13          Amiga Monitor User's Guide                Page 5
  304.  
  305.  
  306.      Alternately, you could get a copy of the ROM Kernal Manuals and read
  307.      about them.  
  308.  
  309. K3     3.5 Page     
  310. M
  311.      The 'Page' menu allows you to page forward or backward, depending
  312.      upon which screen is currently being displayed. Paging is currently
  313.      implemented only for the 'Open Files' display and the 'View Data'
  314.      display. On other screens, these menu items are disabled. For the
  315.      'Open Files' display, they are enabled only when there is more than
  316.      one screen's worth of open files to display.  
  317.  
  318. K3     3.6 Update Rate    
  319. M
  320.      The 'Update Rate' menu allows you to change the rate at which the
  321.      screen is updated. These vary from 1 second updates to 60 second
  322.      updates.  
  323.  
  324. K3     4.0 Implementation Notes    
  325. M
  326.      AmigaMon was written in 'C' and at this writing includes about 2500
  327.      lines of code.  Version 1.13 was compiled using the Aztec 3.4
  328.      compiler.  Previous versions were compiled with the Lattice V3.03
  329.      compiler and linked using Blink Version 5.7.  
  330.  
  331. K3     5.0 Future Enhancements    
  332. M
  333.      The future enhancements listed below are not commitments. Whether a
  334.      particular item gets implemented will depend upon a number of
  335.      factors. If I get a lot of requests for a specific enhancement, that
  336.      will (or it should!) influence whether it gets done. How easy a
  337.      particular item is to do will also have a lot to do with whether it
  338.      gets done. In any case, if you can think of anything you think fits
  339.      in with AmigaMon and you want to see it added to the list below, let
  340.      me know.  
  341.  
  342.      o - If there were sufficient demand for it, I'll put in a
  343.          dis-assembler so you can view memory as both data or code.  
  344.  
  345.      o - I think there is a way to block an active task; i.e. shut a task
  346.          down so that it doesn't compete for CPU. You would also be able
  347.          to UN-block it. This  might be useful. If you think it would be
  348.          nice, let me know, and I'll put it  on my to do list.  
  349.  
  350.      o - The active task display should be modified so that tasks don't
  351.          jump around just because they happen to appear in a different
  352.          queue. They should be sorted by the address of their Task
  353.          structures. That way, they wouldn't all the time be jumping
  354.          around and the display would be more readable.  
  355.  
  356.      o - Also for the task display, it would be nice to display the task
  357.          size (i.e.  the amount of RAM that it consumes). This would be a
  358.  
  359.  
  360.               « Copyright 1986, 1987 Jim Voris. All Rights Reserved
  361.  
  362.  
  363.      Version 1.13          Amiga Monitor User's Guide                Page 6
  364.  
  365.  
  366.          display of the RAM that the Exec knew that the task was using and
  367.          wouldn't include the RAM that the task had alloc'ed after
  368.          startup.  
  369.  
  370.      o - It would be nice to have a separate display page to display
  371.          particulars about a specific task. Information would include such
  372.          things as current register contents, and the state of various
  373.          flags defined in the Task structure.  
  374.  
  375.  
  376. K3     6.0 Fixed Bugs    
  377. M
  378.  
  379.      o - In version 1.0, if a long update rate was selected, AmigaMon had
  380.          to wait for that amount of time before it would exit. This has
  381.          been fixed. AmigaMon will exit immediately following the exit
  382.          command.  
  383.  
  384.      o - Version 1.0 Open Files display would crash the Amiga when running
  385.          under WB 1.2.  This has been fixed to some extent in the current
  386.          release. The AmigaMon Open  files display will probably still
  387.          crash when used on an Amiga with a hard disk. This is due to an
  388.          unsatisfactory algorithm used to locate the Open files. There is
  389.          no easy workaround at the moment.  
  390.  
  391.  
  392. K3     7.0 Known Bugs    
  393. M
  394.  
  395.      o - Paging doesn't work well on the Open Files display. The way this
  396.          is supposed to work is if AmigaMon detects that more than one
  397.          pages worth of Open Files information exists, it will enable the
  398.          Next Page menu item (and conditionally the Previous Page item).
  399.          If you then select the Next Page menu item, the next page is
  400.          supposed to be displayed. Well, it used to work right, but
  401.          somewhere it got broken and it hasn't been fixed yet. The
  402.          workaround is not to have so many files open at once. The bug is
  403.          relatively harmless, (i.e. it won't crash the program or your
  404.          system), but it's a nuisance.  
  405.  
  406.      o - Paging is unimplemented on other displays except for the View
  407.          memory display. This is not so much a bug as an unimplemented
  408.          feature.  
  409.  
  410.      o - AmigaMon has not been tested on a system with FAST memory. If it
  411.          works please let me know.  
  412.  
  413.      o - AmigaMon has not been tested on a system with hard disks. It is
  414.          very  likely that AmigaMon will crash when viewing Open Files on
  415.          a system with a hard disk. 
  416.  
  417.  
  418.  
  419.  
  420.               « Copyright 1986, 1987 Jim Voris. All Rights Reserved
  421.  
  422.  
  423.  
  424.  
  425.  
  426.      % 
  427.                                Table Of Contents
  428.  
  429.                            Amiga Monitor Version 1.13
  430.  
  431.      PREFACE.........................................................    1
  432.  
  433.      1.0 Introduction    ............................................    2
  434.  
  435.      2.0 General Description   ......................................    2
  436.  
  437.      3.0 Options    .................................................    3
  438.         3.1 Project    ..............................................    3
  439.         3.2 Monitor    ..............................................    3
  440.         3.3 View    .................................................    4
  441.         3.4 Set    ..................................................    4
  442.         3.5 Page    .................................................    5
  443.         3.6 Update Rate   ...........................................    5
  444.  
  445.      4.0 Implementation Notes   .....................................    5
  446.  
  447.      5.0 Future Enhancements   ......................................    5
  448.  
  449.      6.0 Fixed Bugs   ...............................................    6
  450.  
  451.      7.0 Known Bugs   ...............................................    6
  452.  
  453.       
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.                                      - I -
  481.  
  482.